---
title: "Grid State"
---

This section covers saving and restoring the grid state, such as the filter model, selected rows, etc.

## Saving and Restoring State

The following buttons log saving and restoring state to the developer console.

{% gridExampleRunner title="Grid State" name="grid-state"  exampleHeight=630 /%}

The initial state is provided via the grid option `initialState`. It is only read once when the grid is created.

```{% frameworkTransform=true %}
const gridOptions = {
    initialState: {
        filter: {
            filterModel: { 
                year: {
                    filterType: 'set',
                    values: ['2012'],
                }
            }
        },
        columnVisibility: {
            hiddenColIds: ['athlete'],
        },
        rowGroup: {
            groupColIds: ['athlete'],
        }
    }
}
```

The current grid state can be retrieved by listening to the state updated event, which is fired with the latest state when it changes, or via `api.getState()`.

The state is also passed in the [Grid Pre-Destroyed Event](./grid-lifecycle/#grid-pre-destroyed), which can be used to get the state when the grid is destroyed.

{% apiDocumentation source="grid-events/events.json" section="miscellaneous" names=["stateUpdated", "gridPreDestroyed"] /%}

## State Contents

The following is captured in the grid state:

* [Aggregation Functions](./aggregation/) (column state)
* [Opened Column Groups](./column-groups/)
* [Column Order](./column-moving/) (column state)
* [Pinned Columns](./column-pinning/) (column state)
* [Column Sizes](./column-sizing/) (column state)
* [Hidden Columns](./column-properties/#reference-display-hide) (column state)
* [Column Filter Model](./filtering/)
* [Advanced Filter Model](./filter-advanced/#filter-model--api)
* [Focused Cell](./keyboard-navigation/) ([Client-Side Row Model](./row-models/) only)
* [Current Page](./row-pagination/)
* [Pivot Mode and Columns](./pivoting/) (column state)
* [Cell Selection](./cell-selection/)
* [Row Group Columns](./grouping/) (column state)
* [Expanded Row Groups](./grouping-opening-groups/)
* [Row Selection](./row-selection/) (retrievable for all row models, but can only be set for [Client-Side Row Model](./row-models/) and [Server-Side Row Model](./row-models/))
* [Pinned Rows](./row-pinning)
* [Side Bar](./side-bar/)
* [Sort](./row-sorting/) (column state)

{% note %}
When restoring the current page using the [Server Side Row Model](./server-side-model/) or [Infinite Row Model](./infinite-scrolling/),
additional configuration is required:

* For the Server Side Row Model - set the `serverSideInitialRowCount` property to a value which includes the rows to be shown.
* For the Infinite Row Model - set the `infiniteInitialRowCount` property to a value which includes the rows to be shown.

{% /note %}

All state properties are optional, so a property can be excluded if you do not want to restore it.

If applying some but not all of the column state properties, then `initialState.partialColumnState` must be set to `true`.

The state also contains the grid version number. When applying state with older version numbers, any old state properties will be automatically migrated to the current format.

The grid state is designed to be serialisable, so any functions will be stripped out. For example, aggregation functions should be [Registered as Custom Functions](./aggregation-custom-functions/#registering-custom-functions) to work with state rather than being set as [Directly Applied Functions](./aggregation-custom-functions/#directly-applied-functions).

{% interfaceDocumentation interfaceName="GridState" /%}

## Setting State

The best way to restore grid state is via initial state as described above. However, it is also possible to restore state on an existing grid via `api.setState(state)`.

{% note %}
`setState` should only be used to restore grid state. The grid does not support being used as a controlled component, so do not call this on every state update.
{% /note %}

{% gridExampleRunner title="Setting State" name="set-state"  exampleHeight=630 /%}

It is possible to maintain the existing state for individual state contents by passing a second argument to `setState` that contains the top-level properties to ignore. E.g. `api.setState(state, ['filter'])` will maintain the existing filter state in the grid.

## Converting Column State to Grid State

State retrieved via the [Column State](./column-state/) APIs can be converted into grid state via the helper functions `convertColumnState` and `convertColumnGroupState`.

```
const state = {
    ...convertColumnState(columnState),
    ...convertColumnGroupState(columnGroupState)
};
```
